Language Reference / Exceptions
What References Are
References in PHP are a means to access the same variable content by different names.
What References Do
There are three basic operations performed using references
- assigning by reference
- passing by reference
- returning by reference
Assign By Reference
PHP references allow you to make two variables refer to(參考) the same content. Meaning, when you do:
<?php
$a =& $b;
?>
$a and $b are completely equal here. $a is not pointing to $b or vice versa. $a and $b are pointing to the same place.
If you assign, pass, or return an undefined variable by reference, it will get created.
Examples: Using references with undefined variables, If you assign, pass, or return an undefined variable by reference, it will get created.
<?php
function foo(&$var) { }
foo($a); // $a is "created" and assigned to null // passing by reference
$b = array();
foo($b['b']);
var_dump(array_key_exists('b', $b)); // bool(true)
/*
array(1) {
["b"]=>
NULL
}
*/
$c = new StdClass;
foo($c->d);
var_dump(property_exists($c, 'd')); // bool(true)
/*
object(stdClass)#1 (1) {
["d"]=>
NULL
}
*/
?>
Warning
If you assign a reference to a variable declared global inside a function, the reference will be visible only inside the function. You can avoid this by using the $GLOBALS array.
Example: Referencing global variables inside functions
<?php
$var1 = "Example variable";
$var2 = "";
function global_references($use_globals)
{
global $var1, $var2;
if (!$use_globals) {
$var2 =& $var1; // visible only inside the function
} else {
$GLOBALS["var2"] =& $var1; // visible also in global context
}
}
global_references(false); // global inside a function, the reference will be visible only inside the function
echo "var2 is set to '$var2'\n"; // var2 is set to ''
global_references(true);
echo "var2 is set to '$var2'\n"; // var2 is set to 'Example variable'
?>
If you assign a value to a variable with references in a foreach statement, the references are modified too.
Example: References and foreach statement
<?php
$ref = 0;
$row =& $ref;
foreach (array(1, 2, 3) as $row) {
// do something
}
echo $ref; // 3 - last element of the iterated array
?>
While not being strictly an assignment by reference, expressions created with the language construct array() can also behave as such by prefixing & to the array element to add. Example:
<?php
$a = 1;
$b = array(2, 3);
$arr = array(&$a, &$b[0], &$b[1]);
$arr[0]++; $arr[1]++; $arr[2]++;
/* $a == 2, $b == array(3, 4); */
?>
however, that references inside arrays are potentially dangerous. Doing a normal (not by reference)
<?php
/* Assignment of scalar variables */
$a = 1;
$b =& $a;
$c = $b;
$c = 7; //$c is not a reference; no change to $a or $b
/* Assignment of array variables */
$arr = array(1);
$a =& $arr[0]; //$a and $arr[0] are in the same reference set
$arr2 = $arr; //not an assignment-by-reference!
$arr2[0]++;
/* $a == 2, $arr == array(2) */
/* The contents of $arr are changed even though it's not a reference! */
?>
Pass By Reference
The second thing references do is to pass variables by reference. This is done by making a local variable in a function and a variable in the calling scope referencing the same content. Example:
<?php
function foo(&$var)
{
$var++;
}
$a=5;
foo($a); // $a = 6
?>
Passing by Reference
You can pass a variable by reference to a function so the function can modify the variable. The syntax is as follows:
<?php
function foo(&$var)
{
$var++;
}
$a=5;
foo($a);
// $a is 6 here
?>
There is no reference sign on a function call - only on function definitions(foo(&$var)). Function definitions alone(單獨) are enough to correctly pass the argument by reference.
PHP 5.3.0, you will get a warning saying that "call-time pass-by-reference" is deprecated when you use & in foo(&$a);
PHP 5.4.0, call-time pass-by-reference was removed, so using it will raise a fatal error.
following things can be passed by reference:
- Variables, i.e. foo($a)
- New statements, i.e. foo(new foobar())
- References returned from functions, i.e.:
Examples:
<?php
function foo(&$var)
{
$var++;
}
function &bar()
{
$a = 5;
return $a;
}
foo(bar());
?>
other expressions should be passed by reference, as the result is undefined. For example, the following examples of passing by reference are invalid:
Examples:
<?php
function foo(&$var)
{
$var++;
}
function bar() // Note the missing &
{
$a = 5;
return $a;
}
foo(bar()); // Produces fatal error as of PHP 5.0.5, strict standards notice
// as of PHP 5.1.1, and notice as of PHP 7.0.0
foo($a = 5); // Expression, not variable
foo(5); // Produces fatal error
?>
Returning References
Returning by reference is useful when you want to use a function to find to which variable a reference should be bound. Do not use return-by-reference to increase performance. The engine will automatically optimize this on its own. Only return references when you have a valid technical reason to do so. To return references, use this syntax:
<?php
class foo {
public $value = 42;
public function &getValue() {
return $this->value;
}
}
$obj = new foo;
$myValue = &$obj->getValue(); // $myValue is a reference to $obj->value, which is 42.
$obj->value = 2;
echo $myValue; // prints the new value of $obj->value, i.e. 2.
?>
the property of the object returned by the getValue function would be set, not the copy, as it would be without using reference syntax
Examples 1:
<?php
function &collector() {
static $collection = array();
return $collection;
}
$collection = &collector();
$collection[] = 'foo';
?>
Examples: To pass the returned reference to another function expecting a reference you can use this syntax:
<?php
function &collector() {
static $collection = array();
return $collection;
}
array_push(collector(), 'foo');
var_dump(collector());
/*
array(1) {
[0]=>
string(3) "foo"
}
*/
?>
Note => that array_push(&collector(), 'foo'); will not work, it results in a fatal error.
Unsetting References
When you unset the reference, you just break the binding between variable name and variable content. This does not mean that variable content will be destroyed.
Examples:
$a = 1;
$b = & $a;
unset($a);
var_dump($b); // 1
won't unset $b, just $a